home *** CD-ROM | disk | FTP | other *** search
/ Software Vault: The Gold Collection / Software Vault - The Gold Collection (American Databankers) (1993).ISO / cdr11 / apique.zip / APIQUEST.TEC
Text File  |  1993-06-26  |  13KB  |  339 lines
  1. ID:AQ DESQview API: Most Common Questions
  2. Quarterdeck Technical Note #119                       Filename: APIQUEST.TEC
  3. by Quarterdeck Developer Support                    CompuServe: APIQUE.ZIP
  4. Last revised:  3/19/93                                Category: API
  5.  
  6. Subject: The ten most commonly asked questions by users of the DESQview
  7.          Application Program Interface (API).
  8.  
  9.  
  10. 1. THE CURSOR DOESN'T MOVE OR IT SITS IN THE UPPER RIGHT HAND CORNER:  WHAT
  11. COULD BE WRONG?  or, I GET VIDEO CORRUPTION WHEN WRITING STRINGS OUT FROM MY
  12. API PROGRAM; IS THIS RELATED?
  13.  
  14. API programs should always have the "Writes Text Directly to Screen",
  15. "Displays Graphics Information" and "Virtualize Text/Graphics" fields of their
  16. DVP's (PIF) all set to NO.
  17.  
  18. The problems resulting from setting these fields to values other than NO can
  19. vary.  The most typical effect is the cursor not moving when text is being
  20. typed.  Another more extreme problem might be seen when text strings sent from
  21. an API application to a window become garbled.  These fields are the first
  22. things to check when you experience problems with an API application.
  23.  
  24. -----------------------------------------------------------------------------
  25.  
  26. 2.  WHEN I TRY TO REASSEMBLE API1.ASM WITH BORLAND'S TASM I GET A LOT OF
  27. ERRORS.
  28.  
  29. API1.ASM was written more with MASM in mind.  You can get API1.ASM to assemble
  30. by using the TASM parameters /JQUIRKS (which allows for some of the quirks
  31. that MASM has) and /MX (which eliminates many of the problems with case
  32. sensitivity on global symbols.)  An example of this would be:
  33.  
  34.      tasm /jquirks /mx api1.asm
  35.  
  36. This will result in 7 warnings but will produce a usable API1.OBJ.
  37.  
  38. ------------------------------------------------------------------------------
  39.  
  40. 3.  HOW DO THE API FUNCTIONS FOR PUSHKEY AND PUTKEY WORK?
  41.  
  42. The API direct calls of PUSHKEY and PUTKEY seem to be difficult for some users
  43. of the DESQview API.  These functions are simple and require only a few things
  44. to be kept in mind in order to work:
  45.  
  46.     * The keys that are sent will be in HEX.  These codes are listed on pages
  47. 213-214 of the API manual.  All of the standard and extended keys are listed.
  48.  
  49.     * The "DESQ" key's scan/key code is FC00h.  CTRL-ALT-DEL is FE00h.
  50.  
  51.     * Scripts can NOT be played back by using the PUTKEY function, but they
  52. WILL be played back with the PUSHKEY function.
  53.  
  54.     * When using PUSHKEY, if you have several keys to push they must be pushed
  55. in the opposite order that you want them seen.  Use API_BEGINC and API_ENDC,
  56. which will create an uninterrupted "critical region", to insure that they do
  57. not get out of order.  API_PUTKEY does not require the use of critical regions
  58. or opposite ordering of the keys to be "put".
  59.  
  60. Following is a C program that shows the proper setup/execution of
  61. PUSHKEY/PUTKEY.
  62.  
  63. Note:  when using Clipper with the DESQview API you must use the
  64. Clipper/DESQview API function API_DEC to convert the hex number to decimal.
  65. Use the following lines as replacements to the C function lines for similar
  66. functionality:
  67.  
  68.  *Begin Clipper specific routine
  69.      keyout = api_dec("FC00")
  70.      api_putkey (tsk_me(),keyout)
  71.  *End Clipper specific routine
  72.  
  73.  
  74. /* PUT/PUSHKEY using the DESQview API */
  75. #include <stdio.h>
  76. #include "dvapi.h"
  77.  
  78. #define REQUIRED 0x200 + 23
  79.  
  80. int  version;
  81. main () {
  82.   version = api_init();
  83.   if (version < REQUIRED) {
  84.     printf ("This program requires DESQview version %d.%02d or
  85. later.\n",
  86.              REQUIRED/256,REQUIRED%256);
  87.     }
  88.   else {
  89.    api_level (REQUIRED);
  90.  
  91.    api_beginc();         /* Note the critical section.           */
  92.    api_pushkey (0x184F); /* Oposite ordering will produce        */
  93.    api_pushkey (0xfc00); /* the DESQ key then the letter O       */
  94.    api_endc();           /* Be sure to end the critical section! */
  95.  
  96.    api_putkey (win_me(),0x184F); /* Supply api_putkey with the   */
  97.  /* window handle and the key scan code/character code.          */
  98.  /* In this case we use the api function  win_me() to supply     */
  99.  /* api_putkey with the name of the window this program will be  */
  100.  /* running in, as opposed to another applications window        */
  101.        }
  102.   api_exit();
  103.  }
  104.  
  105. ------------------------------------------------------------------------------
  106.  
  107. 4.  HOW CAN I TELL IF OTHER TASKS ARE RUNNING?
  108.  
  109. The best approach to check and see if other tasks are running is to write an
  110. XDI (External Device Interface) driver and keep track of a task's creation and
  111. termination.  For further information on the XDI interface to DESQview, you
  112. can consult the DESQview API Reference manual; or for a general overview,
  113. obtain the XDI.TEC technote from Quarterdeck Office Systems.
  114.  
  115. -------------------------------------------------------------------------------
  116.  
  117. 5.  HOW ARE HARDWARE INTERRUPTS HANDLED UNDER DESQVIEW?
  118.  
  119. If the interrupt is requested and interrupts are enabled then the following
  120. things must be true for the interrupt to happen:
  121.  
  122.      * This particular interrupt must not be masked out.
  123.      * No interrupt of higher priority is in service at the time.
  124.  
  125. DESQview installs its own handler (called the DV Diverted handler) for all
  126. hardware interrupts except for the timer interrupt which is undiverted by DV.
  127. DV's handler switches onto an internal stack, determines which task should be
  128. given the interrupt, then sets up that task's map and SOME of its state, and
  129. calls the task's handler.  The window's handler (if present) may usurp the
  130. interrupt or preprocess it and pass it along or pass it along and postprocess
  131. it.
  132.  
  133. DV passes along the timer interrupt to the currently executing window and then
  134. does post processing (including time slicing).
  135.  
  136. The handler in place before DESQview may be a TSR or device driver, a DOS
  137. stack or the BIOS, or a combination of any of the above.
  138.  
  139. DESQview gets ALL the hardware interrupts before any application loaded within
  140. DESQview.  DESQview accomplishes this by programming the 8259A Programmable
  141. Interrupt Controller (PIC) so that all hardware interrupts are diverted to a
  142. different set of interrupt vectors.  When a hardware interrupt occurs,
  143. DESQview will receive the interrupt.  It will then determine which process
  144. hooked that interrupt and map it in.  It will then switch to an internal stack
  145. and pass control to that process's handler.  DESQview switches stacks because
  146. the process that is being interrupted may have a small stack.  DESQview's
  147. stack is fairly large so you should not have stack space problems in your
  148. handler.  However, if your handler uses more than 100 bytes of stack space you
  149. should switch to your own stack.
  150.  
  151. ------------------------------------------------------------------------------
  152.  
  153. 6.  CAN I MAKE DESQVIEW API CALLS IN MY DOS EXTENDED PROGRAM?
  154.  
  155. Typically this is not possible.  DESQview's API calls must be made in real
  156. mode at this time.  Since using a DOS extender puts the machine in protected
  157. mode the API calls will not work.  Some DOS extenders include functions that
  158. let you make real mode calls from within your DOS extended program, but you
  159. will have to refer to your documentation for this procedure, and it is
  160. unsupported by Quarterdeck Developer Support at this time.
  161.  
  162. --------------------------------------------------------------------------
  163.  
  164. 7.  WHAT ARE THE FOUR LEVELS OF PROTECTION UNDER DESQVIEW, AND WHAT ARE THEIR
  165. EFFECTS?
  166.  
  167. 0 - none
  168.  
  169. 1 - DESQview watches to see if a program has locked interrupts for a long time
  170. and notifies the user.  It entails no performance loss and only 1/2K memory
  171. hit (from system memory), but only works on the PS/2 Model 80 and Compaq
  172. machines.
  173.  
  174. 2 - DESQview watches to see if a program writes to memory outside its region
  175. and posts a message.  DESQview doesn't spot programs that do jumps to
  176. different regions.  This option is fairly effective but will probably affect
  177. performance noticeably.
  178.  
  179. 3 - DESQview gets in the way of everything to check if a program even does a
  180. jump to another region.  Some programs won't even run under this burden
  181. (especially well-behaved ones that make calls to DOS and the BIOS), and
  182. performance will be impeded, but it should be pretty safe, barring TSR
  183. problems.  Performance degrades greatly.
  184.  
  185. ------------------------------------------------------------------------------
  186.  
  187. 8.  CAN I USE CRITICAL REGIONS TO LOCK OUT MULTITASKING?
  188.  
  189. Yes, but there are some things that you should try to avoid.  The critical
  190. section should only be a few instructions long and avoid loops that would lock
  191. out multitasking for an unreasonable amount of time.  You should also note the
  192. fact that interrupts are not received by the other processes that are running
  193. and thus could result in loss of information, or, worse, system lockup if the
  194. critical region is too large.
  195.  
  196. ------------------------------------------------------------------------------
  197.  
  198. 9.  WHAT ARE THE CURRENT VERSIONS OF THE APIS?
  199.  
  200.  Product                Codes       Version
  201. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  202.  API C Library          API-C-LIB   1.30
  203.   W/Reference           API-REF/C   1.30
  204.   Toolkit               API-C-TKT   1.30
  205.  
  206.  API Pascal Library     API-P-LIB   1.10
  207.   W/Reference           API-REF/P   1.10
  208.   Toolkit               API-P-TKT   1.30
  209.  
  210.  API Clipper Library    API-L-LIB   1.01
  211.   W/Reference           API-REF/L   1.01
  212.   Toolkit               API-L-TKT   1.01
  213.  
  214.  API Basic Library      API-B-LIB   1.01
  215.   W/Reference           API-REF/B   1.01
  216.   Toolkit               API-B-TKT   1.01
  217.  
  218.  API Dbase Library      API-D-LIB   1.00
  219.   W/Reference           API-REF/D   1.00
  220.   Toolkit               API-D-TKT   1.00
  221.  
  222.  API Reference Manual   API-REF     1.20
  223.  API Panel Designer     API-PANEL   1.01
  224.  API Debugger           API-DEBUG   1.10
  225.  
  226.  
  227. ------------------------------------------------------------------------------
  228.  
  229. 10.  HOW CAN I READ THE TEXT SCREEN OF ANOTHER APPLICATION?
  230.  
  231. This is possible if you place an asterisk in the 'shared program pathname'
  232. field of all of the DVPs associated with the call to read the screen.  A C
  233. example of how this is possible is given below:
  234.  
  235.  /*A simple example showing the use of DESQview's API win_read() function *
  236. Note: make sure to place an asterisk in the 'shared program pathname' field *
  237. of any of the DVPs associated with the win_read(); i.e., if program 'A' * will
  238. be reading the window of programs 'B' and 'C', place an asterisk in all *
  239. three DVPs of all three programs. */
  240.  
  241.  
  242. #include <stdio.h>
  243. #include "dvapi.h"
  244.  
  245. #define required 0x21a     // DESQview 2.26 required
  246.  
  247. void main (int argc, char *argv[]);
  248. int readpif (char *fname, char *buffer, unsigned size);
  249.  
  250.       pifbuf[500];
  251.  
  252.      char *buffer;
  253.      int   buflng;
  254.      int  i     ;
  255.  
  256. void main (int argc, char *argv[])
  257. {
  258.    ulong apphan;
  259.  
  260.    uint  tot,
  261.          avail,
  262.          lrg;
  263.  
  264.    int version = api_init();
  265.    if(version < required)
  266.    {
  267.       printf("\n\nThis Program Requires DESQview Version %d.%02d or Later To
  268. Run!\n\n",\
  269.       required/256,required%256);
  270.       exit(1);
  271.    }
  272.    else
  273.    {
  274.       api_level(required);
  275.       if (argc > 2)
  276.       {
  277.          strupr(argv[2]);
  278.       }
  279.  
  280.       if(!readpif(argv[1],pifbuf,416))
  281.       {
  282.          printf("\nERROR: Bad Or Missing %s.\n",argv[1]);
  283.          api_exit();
  284.          exit(1);
  285.       }
  286.  
  287.       apphan = app_start(pifbuf,416);
  288.       if (!apphan)
  289.       {
  290.          printf("\n\nError Starting Application.\n\n");
  291.          api_exit();
  292.          exit(1);
  293.       }
  294.       else
  295.       {
  296.  
  297.      api_pause();
  298.           api_pause();
  299.           api_pause();
  300.           api_pause();
  301.  
  302.         win_cursor(apphan,0,0);
  303.  
  304.         for (i; i <= 25;i++)
  305.                {
  306.  
  307.                 win_cursor(apphan,1,0);
  308.  
  309.                 win_read(apphan,&buffer,&buflng);
  310.                 win_printf(win_me(),"%s  %d",buffer,buflng);
  311.                }
  312.  
  313.           printf("\n\nApplication Started. Process ID:%lu\n\n",apphan);
  314.       }
  315.       api_exit();
  316.       exit(0);
  317.    }
  318. }
  319.  
  320. int readpif (char *fname, char *buffer, unsigned size)
  321. {
  322.      FILE *handle;
  323.      if ((handle = fopen(fname,"rb")) == 0)
  324.           return 0;
  325.  
  326.      if (fread (buffer, size, 1, handle) != 1)
  327.           return 0;
  328.  
  329.      fclose (handle);
  330.      return 1;
  331. }
  332.  
  333.   ************************************************************************
  334.   *          Trademarks are property of their respective owners.         *
  335.   *This technical note may be copied and distributed freely as long as it*
  336.   *is distributed in its entirety and it is not distributed for profit.  *
  337.   *          Copyright (C) 1992 by Quarterdeck Office Systems            *
  338.   ************************ E N D   O F   F I L E *************************
  339.